Night Owl 6

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 031a / zd86_10.zip / ZD86.DOC < prev next >

Wrap

Text File | 1991-03-20 | 76KB | 2,179 lines

ZanySoft Debugger Version 1.0 by Christopher Kirmse March 20, 1991 Enclosed, either on the disk or in an archive file you have received, you should find the following files: ZD86.COM The ZanySoft debugger, unregistered version. ZD86.NEW List of changes since version 1.0 ZD86.DOC This documentation - includes registration form. EXAMPLE.BAT A batch file to use in the tutorial along with REVERSE.*. REVERSE.ZDV ZanySoft Debugger Variable Window file for REVERSE.COM. REVERSE.ASM Source code to REVERSE.COM REVERSE.Z86 ZanySoft symbol file for REVERSE.COM. REVERSE.COM A sample program to be used with the tutorial. LST-Z86.EXE A utility to convert .Lst files to .Z86 ZanySoft symbol files. SYM-Z86.EXE A utility to convert .Sym files to .Z86 ZanySoft symbol files. Registered users will also find the following files, in the subdirectory REGONLY: ZD86REG.COM The ZanySoft debugger, registered version. MAP-Z86.EXE A utility to convert .Map files to .Z86 ZanySoft symbol files. LISTZ86.EXE A utility to list all symbols in a .Z86 ZanySoft symbol file. ZD86UPGR.EXE A utility to copy all configuration information from one copy of ZD86 to another. ZMACROS.EXE A utility to list all the macros in a copy of ZD86. Please remember, ZD86 is Shareware. This means that I depend on you to register ZD86 if you use it. It also means that you are free to copy all of the unregistered ZD86 package to anyone who wants it--in fact, I encourage it! After all, that is my only means of distribution. For more information, read section 1.2 of this documentation. A convenient registration form is included on the very last page of the documentation, or just run ZD86 and print out a registration form from there! To get in contact with my besides through the mail, you can call over the modem at (703) 866-4452, 8-n-1. At the main menu, type "J ZanySft" without the quotes, and enter a message to Chris Kirmse. This is a quick way to give bug reports, ask about upgrading, or just to see what's new at ZanySoft. Table of Contents 1.0 ZD86 Overview . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Features . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Registration - Terms and Conditions . . . . . . . . 3 2.0 Quick Tour . . . . . . . . . . . . . . . . . . . . . . . 4 2.1 ZD86 in a Nutshell . . . . . . . . . . . . . . . . . 4 2.2 Example . . . . . . . . . . . . . . . . . . . . . . 6 3.0 Detailed Description . . . . . . . . . . . . . . . . . . 9 3.1 General Operation . . . . . . . . . . . . . . . . . 9 3.1.1 Debugging . . . . . . . . . . . . . . . . . . 9 3.1.2 Navigation / Commands . . . . . . . . . . . 12 3.2 Windows . . . . . . . . . . . . . . . . . . . . . 16 3.2.1 Code Window . . . . . . . . . . . . . . . . 16 3.2.2 Register Window . . . . . . . . . . . . . . 17 3.2.3 Stack Window . . . . . . . . . . . . . . . 18 3.2.4 Dump Window . . . . . . . . . . . . . . . . 19 3.2.5 Variable Window . . . . . . . . . . . . . . 20 3.2.6 Output Window . . . . . . . . . . . . . . . 22 3.3 Configuring ZD86 . . . . . . . . . . . . . . . . . 23 3.4 Advanced Operation . . . . . . . . . . . . . . . . 25 3.4.1 Macros . . . . . . . . . . . . . . . . . . 25 3.4.2 Graphics Debugging . . . . . . . . . . . . 26 4.0 Special Notes . . . . . . . . . . . . . . . . . . . . . 27 4.1 Disassembly, Moving Backwards . . . . . . . . . . 27 4.2 Procedure Step Runaway . . . . . . . . . . . . . . 27 4.3 Status Line Help . . . . . . . . . . . . . . . . . 27 4.4 Symbolic Label Offsets . . . . . . . . . . . . . . 27 4.5 Symbols non-Case Sensitive . . . . . . . . . . . . 27 5.0 Utilities . . . . . . . . . . . . . . . . . . . . . . . 29 5.1 Lst-Z86 . . . . . . . . . . . . . . . . . . . . . 29 5.2 Sym-Z86 . . . . . . . . . . . . . . . . . . . . . 29 5.3 Map-Z86 . . . . . . . . . . . . . . . . . . . . . 29 5.4 ListZ86 . . . . . . . . . . . . . . . . . . . . . 30 5.5 Zmacros . . . . . . . . . . . . . . . . . . . . . 30 5.6 ZD86upgr . . . . . . . . . . . . . . . . . . . . . 30 6.0 Registration Form . . . . . . . . . . . . . . . . . . . 31 1.0 ZD86 Overview ----------------- 1.1 Features ------------ ZD86 is a full featured, professional quality Assembler Debugging Environment, which provides Symbolic Debugging for most common Assemblers, including A86, MASM, TASM, etc. The symbolic debugging capability displays and highlights your statement labels and variable names where you have placed them in your code. It is a powerful tool for the serious assembler developer yet friendly enough for the PC enthusiast experimenting with assembly language. ZD86 provides a full range of options for executing your program in a controlled environment. These options include single and procedure step, execute to breakpoint or statement and execute to cursor location. The environment provides for simultaneous display windows of code, memory, preset variables (including symbolic designation), stack, registers, and the user application screen. Windows can be closed, opened, moved, resized, and displayed with different colors to provide better insight into the code you are debugging or to meet your personal preferences. These and all other configurable settings can be tailored to your needs and saved so that each time you invoke ZD86 your own unique debugging environment will be at your service. All commands are available in menu driven form (Menu Mode) and with intuitive quick-key combinations (Command Mode) to increase productivity as you become more experienced with the environment. ZD86 comes with Macro Define capability and configurable Function Keys to further increase ease of use and productivity. As you are debugging your program you control the register, stack, and memory values. You can change these values by using the convenient editing feature which displays both ASCII and hex. Other helpful features include program preset from within the ZD86 environment, quick statement NOPing, support of EGA/VGA 43/50 line mode, situation dependent on-screen help line, and the capability to print a range of your code to disk or printer. Utilities are included to create the symbol file required for the symbolic capability from an A86 .Sym file, a MASM .Lst file, TASM .Lst file, or a Link/Tlink .Map file (.Map file conversion is not included in the evaluation version but is supplied with the registered version of ZD86). Debugging is a tough job--make sure you have the right tool to handle it--ZD86. And if you use the tool, register it. - 1 - 1.2 Registration - Terms and Conditions --------------------------------------- A convenient registration form is available as a menu selection. Simply select it from the Menu - Help selection, Register Form, and hit Print-Screen on your PC to get a hard copy. Also, a form is included at the end of this document. ZD86 is provided for your individual use, and you are responsible for determining the fitness and usability of the package. You may not resell or modify this package. You may however, make backup copies for yourself and you may make copies to distribute to others for their evaluation and possible registration. You may charge others a small fee for such redistribution. You and any others to whom you distribute copies may execute ZD86 solely for the purpose of evaluation. If you continue to use the software you must register it. I will not be liable for any damages whatsoever arising from evaluation or use of this software, whether registered or unregistered, including but not limited to failure of the software to perform as expected. Registering the current version of ZD86 now will also entitle you to all future releases upon payment of a small update fee. Educational Institutions, Companies, or Government Agencies should contact me directly for volume purchases or site license fees. - 2 - 2.0 Quick Tour -------------- 2.1 ZD86 in a Nutshell ---------------------- When you first enter ZD86 the screen will be displayed according to the default configuration settings. These configuration settings control the placement and size of the windows, display colors, the actions to be taken by all function key combinations, 25 vs. 43/50 line mode, etc. Alt-X will let you quit ZD86 at virtually anytime. On the bottom line of the screen you will notice the status/help line. In this area is shown an abbreviated context sensitive help list of many of the keys that can be pressed and their effect. You can scroll through the choices or hit the highlighted letter of the command desired. Many menus have additional pull-downs to provide additional choices or to get more information. Selections not available (because of other options already chosen or other conditions) appear in subdued color. Escape will also bring you back up from the deepest of menus. You can also use quick-key combinations to get to a Menu selection. Press Alt and the first letter of the menu selection, e.g., Alt-C takes you to Menu Mode and selects the Code option. Pressing any key removes the title display and you are now ready for operation. There are two basic modes of operation, Menu Mode and Command Mode. Press Esc or M to go from Command Mode to Menu Mode and back. In Menu Mode the Menu Bar is activated and you can use the arrow keys to move to the selection of your choice. When you are in Menu Mode the currently active menu selection is highlighted. Enter will select your choice and display a pull down menu. Command Mode is the normal operation mode wherein you run your program, move around the window displays and edit memory locations. S is the single step command, P is procedure step, B sets a breakpoint at the Code Window cursor, etc. Other commands work on the current window: C closes it, R allows you to move the current window with the arrow keys, or to change its size by holding down Ctrl while using the arrow keys. Note that closing a window does not affect the contents, and you can reopen it at any time. It will return to its last position and size. Looking at the screen you see that the status/help line now shows keys that can be used in the Code Window which is in the top left of the screen. Scanning the screen you can see all of the other windows displayed. Each window has its own cursor. If you ran ZD86 with a program name on the command line (if not, hit Alt-F, L and type REVERSE ABC then enter). You will see the code address, hex machine code and the assembler language statements - 3 - for that program. The border of the Code Window is highlighted meaning it is the current window. You can move the display, edit values, or change the location and size of whichever window is current. Hit tab to make a different window current (Ctrl and the first letter of the window, e.g. Ctrl-R, also changes the current window, in this case to the Register Window). The best way to understand ZD86's capabilities is to use it. Make sure you have a backup copy (to get back the default configuration settings for colors, etc.) and try the various capabilities. Note especially the configuration options under the Install Menu selection. Go down through the menus until you see the color display appear and experiment by choosing different combinations with the arrow keys. While in Command Mode, hit W and watch the program execute in walk through mode (until you press another key). Watch the registers, flags, and Variable Window display changing values, while the Code Window shows the program flow. If you are executing Reverse, after a short period of time you will notice changes in the Output Window also. After you have experimented with the ZD86 environment, follow the example in the next section to get an idea of how this environment can help you debug in a specific situation. - 4 - 2.2 Example ----------- The example is designed to illustrate the power of ZD86 and to introduce many of the debugging concepts. To begin the example start ZD86 by typing EXAMPLE at the DOS prompt which will initiate the ZD86 debugger and load in the program REVERSE.COM. The REVERSE program is a small assembler program which takes a character string on its command line and prints it to the screen in reverse order. Hit any key to clear the title screen. You will notice that the Code Window displays a program with several Symbolic Labels. This means that there already is a symbol file named Reverse.Z86 which was automatically loaded. (To create a Symbol File from one of your own programs see the Utilities Section.) The Variable Window also has several items already defined. With the exception of the Symbolic name Reverse_line and its continuation, those items are the standard variable window defaults. The pre-defined Symbolic name Reverse_line indicates that settings for the Variable Window have been saved in a file with the name Reverse.ZDV because it was autoloaded. You can modify the settings for the Variable Window as well as have multiple setting files; see the section on Configuring ZD86 for details. The Output Window shows a portion of the screen where you typed your last instructions in DOS. EXAMPLE was actually a .BAT file which issued the following command: ZD86 Reverse This is a test line. abcdefghijklmnopqrstuvwxyz . Tab to make the Output Window current and use the arrow keys to see the whole line that came from the .BAT file. Note the instruction under the cursor is JMP Past_data. Hit up-arrow and note that the Command and label Main have disappeared. This is because disassembly backwards through memory is not always accurate (See the Section in Special Notes). Hit Ctrl-down-arrow, which causes the disassembly to shift by one byte, to see that we have the correct code once again. Note in the Register Window that the Instruction Pointer (CS:IP) is at xxxx:0100, the statement that has the Symbolic Label Main. xxxx indicates that the segment portion of the address may vary from run to run and from machine to machine. To prove this select Menu - Code selection, Toggle Symbols (either by hitting Esc to enter the menu mode and using the arrow keys or by hitting Alt-C, T)--toggle again to restore the Symbolic Names. Return to Command Mode by hitting Escape. Press S to begin Single Step execution of the Reverse program. Note that the Code Window indicates you are now at the Past_data location and CS:IP is xxxx:0127. Press S again and note that the - 5 - CL register, the lower byte of CX, has been updated with the length of the Command Line string (hex 31 = decimal 49--note the Variable Window of 49 at DS:0080 from the Command Line). Press S several more times until you execute the statement MOV DI,Reverse_line. The register DI has been updated to 017C. Make sure that the Code Window is current (outline is double width, highlighted); if not, hit Tab until it is the current window. Move down the Code Window with the arrow keys and note that the label Reverse_line is at 017C. Move the cursor back up to xxxx:0135. If you are in 25 line mode expand the variable window by hitting Tab multiple times to make it current, press R, depress the Up-arrow key several times, followed by Ctrl-down-arrow several times, then ENTER. Press S several times; watch the different windows as xxxx:0135 REP MOVSB is executed repeatedly. The CX register decrements for each press; DS:SI and ES:DI increment. The Variable Window shows DS:SI being processed and DS:Reverse_line receiving each character being moved. Press S several times after the new characters added to DS:Reverse_line are no longer visible. Select Data, Variable Edit from the Menu (Escape, D, V, or Alt-D, V). Select Down Var Cursor or Up Var Cursor as necessary and hit Enter as necessary to move the Cursor in the Variable Window to the line after DS:Reverse_line. Then select Continue prev and hit Enter. Note the line has now become a continuation line for DS:Reverse_line and you can now see the other characters that were moved. Select Down Var Cursor and Continue Prev several more times to make additional continuation lines. Return to Command Mode (Esc repeatedly until you are out of Menu Mode) and press S several times to see additional characters move one by one. Press P one time. P executes Procedure Step which will execute a subroutine REP or Loop until done (as opposed to one by one with S). Note the remainder of the text from the Command Line has been moved to Reverse_line. Tab to the Variable Window to make it current. Press right-arrow several times; note this makes the entire label name Reverse_line visible and that the continuation lines automatically adjust so that they continue to display the full text. Press R and Ctrl-right-arrow to expand the Variable Window to the right edge of the screen and press Enter. Note that the full text is now visible on one line. Press S several times until you come to the statement Print_line_reversed: PUSH AX. Watch the stack window update as you press S once for each PUSH statement. Press S several more times until you reach xxxx:015C TEST CX,CX. Watch the bottom of the Register Window as you press S once again and note how the flags are updated. Press S several times until you reach xxxx:0166 MOV b[DI],AL. Watch DS:Reverse_line in the Variable - 6 - Window as you press S again and you will see Z appear as the text from the command line is moved in reverse order. Keep pressing S to walk through the loop and see the characters appear one by one in reverse order. After you have seen enough press S until you reach xxxx:0169 LOOP Do_reverse_line and hit P. This will complete the loop and move the remaining text in reverse order into DS:Reverse_line. Press S several times until the statement at xxxx:0175. Press S one more time which executes INT 21h, which performs the DOS service to print the reversed string on the screen. Press Ctrl-O to make the Output Window current and move around it with the arrow keys until you see the reversed string. Press V to view the Output Application Screen and you will also see the reversed string. Press any key to return to the ZD86 Debugging Environment. As you press S watch the values move from the stack to the appropriate registers. Press S until you RETurn to the statement Exit: INT 20h. Press S again and note the Program Terminated Message Box. The program is successfully completed. - 7 - 3.0 Detailed Description ------------------------ 3.1 General Operation --------------------- 3.1.1 Debugging --------------- Debugging features fall into three principal areas: Execution Control, Memory Operations, and General Operations. Controlling execution is one of the most important functions of a debugger and ZD86 has a full range of options. There are four execution modes: Single Step, Procedure Step, Walkthrough, and Go. Single Step causes execution of the program line pointed to by CS:IP (the line indicated by the triangle in the Code Window). Procedure Step has the same effect on single execution statements. On repeats, loops, and calls, Procedure Step executes the required number of times (or the entire procedure) and stops at the next statement. Walkthrough executes Procedure Step after Procedure Step until a key is pressed, it reaches a breakpoint, or it reaches the end of the program. S, P, and W invoke the above execution modes respectively; these execution modes can also be selected from the Menu. The final execution mode, Go, has several options. Go from the Menu or G from Command Mode will run until the end of the program or until it encounters a breakpoint. Breakpoints can be set from Command Mode by pressing B. This causes a breakpoint to be set at the current cursor position in the Code Window. If a breakpoint is already set at the cursor location pressing B causes the breakpoint to be cleared. Toggle Breakpoint in the Menu - Code selection has the same effect. Breakpoints may also be set at a specific address from the Menu by selecting Breakpoint @xxxx:xxxx. A list of currently set Breakpoints can be obtained by choosing Menu - Code selection, List Breakpoints. Two additional Go options are available from the Menu: Go until Cursor which causes execution from the current CS:IP until the statement highlighted by the cursor and Go until Address causes execution from the current CS:IP until the address specified. Breakpoints take precedence over both Go until options and will cause execution to halt if encountered prior to the cursor or address specified. Sometimes during execution of your program, in particular when using the Go option, you may get caught in an infinite loop or runaway that prevents your return to the ZD86 Debugging Environment. The safest way to return is to press Ctrl-break to stop the execution of your program and return to the ZD86 Debugging Environment. This stops your program after the next execution of INT 21h in your program. You can press SysReq (or Alt-SysReq depending on your keyboard) to stop execution of your - 8 - program as well. If your program code was executing you will immediately return; if you were in an interrupt routine, you will need to step through the interrupt in order to return. This is not always successful--you may need to reboot and reload your program in ZD86. Memory Operations consist of displaying areas you need to see and modifying the contents of memory locations. Many of these options are executed from the Menu - Data selection. Dump at DS:SI and Dump at ES:DI are handy ways to set the Dump Window display area to these often used addresses. Display At address (@ from Command Mode) allows you to change the display starting location of the Code, Stack, or Dump Windows to the address specified; the Code, Stack or Dump Window must be the current window as appropriate. Edit from the Menu - Data or Enter while in Command Mode allows you to alter the contents of memory in the current window at the current cursor location. A special edit window appears showing memory contents in both ASCII and hex. The flashing cursor indicates whether you are editing in ASCII or hex; TAB switches between the options. You may save the changes by pressing Enter or discard them by pressing Esc [no, the menu deal]. Fill from the Menu - Data selection allows you to put a single hex byte in an entire memory range, such as to quickly blank out an area. Symbol Value will return the memory address for any symbolic name. Toggle Symbols from the Menu - Code selection allows you to switch the Code Window display back and forth between Symbolic and Address display. General Operations refers to several specialized features of the ZD86 Debugging Environment. These features are generally found under the Menu - Code selection. Move cursor to CS:IP is a quick way to restore the Code Window display to the next executable code statement after you have scrolled through other areas of your code, or if you have directly changed the CS:IP value in the register window. Set CS:IP to cursor is a convenient means of skipping an area of code or causing execution of a specific subroutine that you have scrolled to in the Code Window. Simply find the area you wish to execute; Set CS:IP to Cursor will cause that statement to become the next executable statement. NOPing a statement is another convenient means during debugging of preventing certain code from executing. Simply convert the statement(s) to a NOP, either from the Menu - Code selection, NOP statement, or by pressing N in Command Mode. Executing this command or selecting the Menu option NOP statement causes the statement at the cursor location in the Code Window to be filled with NOPs and moves the cursor to the next statement. Holding down N in Command Mode therefore repeats causing very quick deletion of many statements. - 9 - Restore Registers is a handy "Undo" if you make an error while modifying register values in the Register Window. This command will restore all registers to the value they had after the last executable statement, i.e., before any modifications were made. Finally, Screen Swap from the Menu - Window selection has three options: Always, Never, and Smart which require some explanation. Setting this option controls automatic switching by ZD86 between the User Application Screen and the ZD86 Debugging Environment. In the Always setting the User Application Screen will be shown during the execution of each statement, even if no Input/Output operation is occurring in that statement. This can cause an annoying flicker because of the constant switching between the ZD86 Debugging Environment and the User Application Screen. The Never setting eliminates the flicker by keeping the display as the ZD86 Debugging Environment. If there are Input/Output operations you can monitor them in the Output Window. If the program is awaiting input the left side of the status/help line (bottom line of the screen) will indicate "Running". The third setting, Smart, is a compromise of the above two settings. While Single Stepping it will only go to the User Application Screen on an Input/Output operation. While Procedure Stepping it will go to the User Application Screen on an Input/Output operation or for any loop or procedure call, since these might contain an embedded Input/Output operation. Note that for debugging the VGA 13h graphics mode (by giving ZD86 the switch /vga13h on the command line), you must have the Screen Swap setting set to Always for correct results. (see Section 3.4.2 - Graphics Debugging) - 10 - 3.1.2 Navigation / Commands --------------------------- Moving around in the ZD86 Debugging Environment is straightforward. There are two basic operation modes, Menu Mode and Command Mode. To move between the modes press Esc. In Menu Mode the current Menu selection is highlighted in the Menu bar at the top of the screen. The left and right arrow keys move you across the Menu bar; Enter or down arrow pulls down the first level Menu list. Use the up and down arrows to move within the list; ENTER to select your choice from the list. If your choice has additional options or needs additional information an additional list will appear. Many menu lists will close once you have selected your choice. Some menu lists where you are likely to want to make repeated selections remain open until you explicitly leave them. Repeatedly hit Esc to come up from a menu list until you have left Menu Mode. In Command Mode you can move between and within the windows as well as issue many commands directly using quick-key combinations. The six windows available (simultaneously) are Code, Register, Stack, Output, Dump, and Variable. All windows are updated simultaneously as you execute your program or change the environment. One window, called the "current" window, is indicated by the double width highlighted border. You can change which window is current by hitting Tab or Shift-Tab to cycle through the windows, or by pressing Control and the first letter of the window (Ctrl-S for the Stack window, Ctrl-C for the Code window, etc.). You can move around and edit contents of the window which is current. Moving within the current window is controlled by eight keys; the four arrow keys, Page Up, Page Down, Home, and End. The arrow keys generally are used to move the cursor in the direction indicated. Page Up and Page Down move the entire display within the window so that the previous contents move off the screen and the window will now display the contents immediately below or above the previous contents, respectively. Home moves the cursor to the beginning of the current line; End move the cursor to the end of the current line. In the Code and Variable Windows the left and right arrow keys and Home and End keys shift a portion of the display to the right or left to allow you to see long symbol names. You have complete control over the size and placement on the screen of the six debugging windows. While in Command Mode press R to resize the current window, move it around the screen with the arrow keys, and change its size by pressing the Ctrl-arrow keys. You can also close or open the windows as you see fit. Several of the Windows have special functions which are activated - 11 - by pressing Ctrl and one of the arrow keys. In the Code Window Ctrl-up-arrow and Ctrl-down-arrow adjust the disassembly one byte. This is helpful if the disassembly becomes confused when "backing up" through the code (See Section 4.1 in Special Notes regarding disassembly). In the Register Window Ctrl-up-arrow increments the register whose value is highlighted by the cursor, and Ctrl-down-arrow decrements it. In the Dump Window Ctrl-left-arrow or Ctrl-right-arrow causes the display to shift around the cursor (as opposed to moving the cursor through the display), allowing you to line up the leftmost display position at a meaningful byte boundary. Within any window the Enter key causes a Memory Edit Box to appear allowing you to change memory or registers at the current cursor position. Movement within the Memory Edit Box uses the four arrow keys, Page-up, Page-down, Home and End exactly as described above for the display windows. There are several ways to issue commands. In Command Mode many of the more common commands can be accessed by pressing a single letter key. Other commands can be configured to be activated by a single Function Key or Function Key combination (Shift, Alt, or Ctrl Function Key). See the Configuration Section below. Finally, all commands can be executed by going to the Menu Mode and making appropriate choices from the menu lists. Menu selections can be accessed by hitting Esc to get to Menu Mode and then using the arrow keys to move the selection desired, or you can go directly to the Menu bar selection by typing Alt and the first letter of the selection. For example, Alt-C from Command Mode puts you into Menu Mode with the Code list activated and displayed. The ultimate shortcut for a series of commands that you use frequently is, of course, recording them as a macro. Simply hit Alt-M to start recording, select a number for the macro, and type in the key sequence. Hit Alt-M again to turn macro recording off. Now type Alt and the number you chose for the macro and the entire key sequence will be executed. The commands available from Command Mode are as follows: B - Toggles a breakpoint on/off at the current cursor location in the Code Window. C - Close the current window (removes it from the screen). E - Edit the memory contents at the position indicated by the cursor in the Variable Window. G - Causes execution of the program being debugged starting at the current value of CS:IP and continuing to a breakpoint or the end of the program. H - Display Help Screen. M - Menu Mode N - NOP statement at the cursor position in the Code Window. O - Opens a window; the list of closed windows will pop-up - 12 - for you to select from. P - Procedure Step from the current value of CS:IP R - Resize the current Window. Use the arrow keys to move the window around on the screen. Use Ctrl-arrow keys to change the size of the Window. S - Single Step from the current value of CS:IP. V - View the User Application Screen instead of the ZD86 Debugging Environment. Press any key to return to the debugger display. W - Walk through mode, which is an automated Procedure Step until a key is pressed. Gives a good view of program flow. All windows are updated so you can see registers and memory change. Y - Enter a symbol name and get the offset location, or constant value of the symbol. @ - In the Code, Dump, or Stack window, enter an address and the display in the window will now begin at that address. The above commands are also available via selections from the Menus. Additional commands available only from Menu Mode (unless you configure them as Function key combinations) are as follows: Program Reset - Reloads the current program from disk and resets CS:IP. Load Program - Brings a new .Exe or .Com file into the ZD86 Debugging Environment. Save and Load Var file - Saves (retrieves) the settings for display in the Variable Window. Save .COM file - Allows you to save a .COM file you have modified to disk. Write listing - Writes disassembled code between addresses specified to disk or device. 25 vs. 43/50 line mode - Changes display if you have EGA/VGA Screen Swap - Controls switching to the User Application Screen. Go Until Cursor - Causes program execution to the statement indicated by the cursor in the Code Window. Go Until xxxx:xxxx - Causes program execution to the address indicated. Move Cursor to CS:IP - Change the Code Window display so that the cursor appears at the address CS:IP. Set CS:IP to Cursor - Change the CS:IP register pair to hold the address of the statement shown in the Code Window at the cursor. Toggle Symbols - Turn the display of symbol names on/off. List Breakpoints - List addresses of all currently set breakpoints. Clear All Breakpoints - Deletes all previously set breakpoints. Restore Registers - Reset all registers to the value they had prior to the last program execution. - 13 - Dump at DS:SI - Change the dump window display to begin at address DS:SI. Dump at ES:DI - Change the dump window display to begin at address ES:DI. Edit @xxxx:xxxx - Allows editing of the memory at the address specified. Variable Edit - Allows selection of display items and formats for the variable window. Install - Color Configure, Function key Configure, Other Configure - Allows you to change and save various configurable items. The last two areas, Variable Edit and Install - Color Configure, Function key Configure, Other Configure are part of the configurable debugging environment and are covered in more detail in section 3.3. - 14 - 3.2 Windows ----------- 3.2.1 Code Window ----------------- The Code Window displays your disassembled assembly language code. If you have created a symbol file (see Section V, Utilities) your label names will appear highlighted at the appropriate line in the code, and variable names and labels will appear where they have been used in the assembly statements. The Code Window can be moved to any location on the screen, or removed altogether. The Code Window may be shrunk or expanded to display as many lines of code as you like up to the size of the screen display. Moving within the window is controlled by the arrow keys. Moving beyond the upper or lower window boundaries, or using Page-Up/Page-Down, causes the code to scroll within the window. The location of the next statement to be executed (the CS:IP address) is indicated by a triangle on the left side of the machine code. When you are stepping through your program the display in the Code Window will scroll or change as necessary to display the currently executing statements. While in the Code Window you can examine your code, move the cursor, toggle breakpoints on/off, or move the cursor to a position in the code and choose Menu - Code selection, Go until cursor. When you page-up or scroll off the top of the screen, the disassembly may not be correct (See Special Notes, Section 4.1). Press Ctrl-up-arrow or Ctrl-down-arrow to adjust the disassembly by one byte. Code can be changed from the Code Window by hitting Enter. A Memory Edit Box will pop up; the first byte will be the first byte of the machine instruction at the cursor location. You can change the code in either ASCII or hex mode; the Tab key toggles between the modes. - 15 - 3.2.2 Register Window --------------------- The Register Window displays CS:IP, DS:SI, ES:DI, SS:SP and SS:BP register pairs in hex format segment and offset. The contents of registers AX, BX, CX, DX are displayed in both hex and ASCII. Flag values are shown in the form Upper Case, highlighted = on (set, 1); lower case, not highlighted = off (cleared, 0). The Register Window can be moved to any location on the screen or removed altogether. The size of the Register Window can not be changed. Movement within the Register Window is controlled by the arrow keys. Page up and page down move to the top and bottom of the Register Window respectively. Contents of the Register Window are continuously updated as your program executes. Any register value can be changed by moving the cursor to the value and hitting Enter or Ctrl-arrow keys. A Memory Edit Box will pop up displaying the register and value, highlighting the current digit position. Standard cursor movement keys apply. Type in the new hex value and hit enter. The new value will appear in the Register Window and will be used for subsequent operations. A handy "undo" feature is available from the Menu - Code selection, Restore Registers. This command will restore all registers to the value they had after the last executed statement. - 16 - 3.2.3 Stack Window ------------------ The Stack Window displays the address and value for the stack. The display initially begins with the bottom item displaying the stack at location SS:SP. The Stack Window can be moved to any location on the screen, or removed altogether. The Stack Window may be expanded in height to show more stack contents, but its width is fixed. Moving within the window is controlled by the arrow keys. Moving beyond the upper or lower window boundaries or using Page Up/Page Down causes the stack to scroll within the window. The current location of SS:SP is indicated by a triangle on the right of the stack address (left of the stack value). When you are stepping through your program the contents of the stack will be updated appropriately. The display within the window will also adjust so that location SS:SP will continue to appear in the window as the stack grows or shrinks. The stack contents can be modified by hitting Enter while in the Stack Window. A Memory Edit Box will pop up; the first byte will be the byte that the cursor is on in the Stack Window. Several values may be modified at the same time (Remember the IBM PC stores words in reverse byte order). You can change these values in either ASCII or hex mode; the TAB key toggles between the modes. The blinking cursor appears on the ASCII line in ASCII editing mode and on the hex byte representation in hex editing mode. - 17 - 3.2.4 Dump Window ----------------- The Dump Window displays the contents of an area of memory in both hex and ASCII. The initial area displayed begins at DS:0080 when a program is successfully loaded, thus displaying the program's command line. If a program is not loaded the initial display begins at DS:0000. The Dump Window can be moved to any location on the screen or removed altogether. The Dump Window may be expanded or contracted in both height and width. Moving within the window is controlled by the arrow keys. Moving beyond the upper or lower boundaries or using Page-up/Page-down causes the memory display to scroll within the window. When you are stepping through your program the contents of the Dump Window are updated as appropriate. Memory contents can be modified by hitting Enter while in the Dump Window. A Memory Edit Box will pop up; the first byte will be the byte that the cursor is on in the Dump Window. Several values may be modified at the same time (Remember the IBM PC stores words in reverse byte order). You can change these values in either ASCII or hex mode; the tab key toggles between the modes. The blinking cursor appears on the ASCII line in ASCII editing mode and on the hex byte representation in hex editing mode. - 18 - 3.2.5 Variable Window --------------------- The Variable Window displays the contents of memory at specific memory locations. Up to 44 different memory areas may be displayed simultaneously. The display format can be bytes or words, in hex or decimal, or ASCII characters. You can display one or many contiguous memory locations starting at the segment and offset indicated. The segment and offset can be selected from a menu or by typing in an address. The offset can also be selected by using a variable name (assuming you have created a symbol file - see Section V-Utilities). This last feature is very handy because it displays the variable name as the offset making debugging a lot friendlier. An additional feature is the Continue Previous option which continues the memory display from the previous line of the Variable Window. This is very useful for long strings or arrays. You can have as many continue lines as you like (up to the maximum of 44 display lines) and the display will automatically adjust itself if you change the size of the Variable Window. All of the above references selections that are made from the Menu - Data selection, Var Edit. Several lines have preset default displays (which can be changed) when you enter ZD86. The first two lines of the display are preset to DS:SI and ES:DI respectively. The third and fourth lines are set to DS:0080 and its continuation, which is the program command line area. The setting for DS:0080 is a single decimal byte (this location indicates the command line length) and the continuation line is set for multiple ASCII display to show the actual command line text that was typed. The Variable Window can be moved to any location on the screen or removed altogether. The Variable Window may be expanded or contracted in both height and width. Within the Variable Window, the display can be shifted to allow a larger field for Offset in the case of longer variable names. The Type column in the Variable Window indicates the display format for each address or variable that you have set. The first position is 1 or M indicating single or multiple memory location display. In the second position A indicates ASCII display; a B or W indicates Byte or Word. If B or W is specified it is followed by H or D for hex or decimal. Moving within the window is controlled by the arrow keys. Moving beyond the upper or lower boundary of the screen or using Page-up/Page-down causes the display to scroll within the window. Scrolling will stop when the top or bottom is reached. Small arrows in the border of the window indicate if there is any more displayable area in the direction pointed to. When you are stepping through your program the contents of the Variable Window are updated appropriately. - 19 - Memory contents can be modified by hitting ENTER while in the Variable Window. A Memory Edit Box will pop up; the first byte will be the byte that the cursor is on in the Variable Window. Several values may be modified at the same time (Remember the IBM PC stores words in reverse byte order). You can change these values in either ASCII or hex mode; the TAB key toggles between the modes. The blinking cursor appears on the ASCII line in ASCII editing mode and on the hex byte representation in hex editing mode. - 20 - 3.2.6 Output Window ------------------- The Output Window displays the standard text User Application Screen. The Output Window can be moved anywhere on the screen or removed altogether. The Output Window can be expanded or contracted up to the size of the user screen. The numbers in the center of the bottom border indicate the screen row and column position of the upper left corner display character in the Output Window. The arrow and other cursor control keys can be used to move the display within the window. Small arrows in the border of the window indicate if there is any more displayable area in the direction pointed to. As you step through your program the Output Window is updated as appropriate. It is especially useful in debugging to watch output appearing while at the same time watching register and variable changes in another area of the screen. - 21 - 3.3 Configuring ZD86 ---------------------- One of the more important ZD86 features is its configurability. You have control over the debugging environment and can tailor it in a way that best meets your needs and increases your productivity. You could even have multiple layouts and have a macro to change between them with an Alt-number combination - try pressing Alt-7 (Alt-9 will restore the display). Before you begin experimenting with configuration options, make sure that you have made a backup copy of ZD86 so that you can restore the original settings later if you don't like the settings you have chosen. In general you have the capability to configure Windows, Colors, Function Key assignments, 25 vs. 43/50 line display mode, and miscellaneous items such as shadow and background characters. You may also save all the Variable Window settings. The next time you activate ZD86 you would then have your own unique ZD86 Debugging Environment ready for use. You have complete control over the size and placement on the screen of the six debugging windows. While in Command Mode press R to resize the current window, move it around the screen with the arrow keys, and change its size by pressing the Ctrl-arrow keys. You can also close or open the windows as you see fit. Experiment until you find an arrangement that best suits your needs, then save it using the Menu - Install selection, Save Windows. You can always change the display arrangement easily as the need arises. Colors should be chosen to highlight the items you consider most important. Each window has separate colors for foreground, background, cursor, etc. Follow the list under Menu - Install selection. A color box will appear in the upper left of the screen with a white outline around the current foreground and background selection for the item you are editing. Move the outline around with the arrow keys until you find a suitable color combination. Enter will change to the new color, Esc leaves the old color in effect. Because of all the different items for which colors can be chosen you will need to experiment a bit to find pleasing and sufficiently contrasting color combinations. Save your choices at any time using the Menu - Install selection, Save Colors. Each of the Function Keys can be assigned a different command value. F1 has been preset to Help, but can be reconfigured. The combinations Shift Function Key, Alt Function Key, and Ctrl Function Key are also configurable. To configure the function keys choose Configure Function keys from the list under Menu - Install selection and choose the key assignments by moving - 22 - through the convenient menu provided in the upper left of the screen. Enter will assign the command selected, Esc will cancel the assignment of the command and restore the Function Key to its previous command assignment. Save your choices at any time using the Menu option, Install, Save Function Keys. Variable Window settings are established under the Menu - Data selection, Variable Edit, or by pressing E from command mode. As indicated in the subsequent menu you can specify the Segment and Offset for display at the current cursor position in the Variable Window (Make sure you have the cursor set on a line in the Variable Window that you have not already set up or that you want to change). Under the Offset selection you may type a symbol name instead of an address or register and it will be used in the Variable Window. For each address/variable selected you can choose whether you wish to display ASCII, Hex or Decimal bytes or Words and whether or not you want one or many of your choice displayed. If you choose many, the display will begin at the location specified and continue for the width of the Variable Window. A special feature is the Continue Previous option. This displays memory beginning at the next location following the last location in the previous line. You can thus cause a long variable to wrap within the window so that you can see the entire variable contents even if it is larger than the width of the window. You may continue for as many lines as you like and the continuation lines automatically readjust if you resize the Variable Window. To save the configuration settings of the Variable Window choose the Menu - File selection, Save Var Window. You may save multiple Variable Window configuration files (just change the filename, but the extension must be .ZDV. The default is Program Name.ZDV). Use Menu - File selection, Load Var Window to retrieve Variable Window configuration settings (The default Program Name.ZDV is automatically loaded for you, if it exists, upon loading a program). Miscellaneous items that you can configure include shadow and background variations and case for symbol displays. Follow the list Menu - Install selection, Other Configure. You can save your choices using Save Other Settings. This option also saves the current setting of Screen Swap (smart, always, or never). If you have created any Macros you can save them using the Menu - Install selection, Save Macros. You can save all settings for Windows, Colors, Function Keys, Miscellaneous Items, and Macros at one time with the Menu - Install selection, Save Everything. Note that you must save Variable Window configuration settings from the Menu - File selection, Save Variable Window. - 23 - 3.4 Advanced Operation ---------------------- 3.4.1 Macros ------------ Macros give you the capability to automate a sequence of keystrokes that you use frequently. You can define up to 10 Macros and each can contain up to 100 keystrokes. Macros can be chained together, i.e., Macro 3 in its last keystroke can invoke Macro 4. Thus you can actually automate a sequence of more than 100 keystrokes. Recording a Macro is straightforward. Simply hit Alt-M which invokes Macro recording, select a number for the macro, and then press the sequence of keys that you wish to record. While you are recording your macro, the upper right corner of the screen indicates that you are recording and the number you selected for this Macro (R#). Just to the left of this you will see the Key # in the Macro for the next keystroke to be recorded. When you are finished press Alt-M again to turn Macro recording off. To execute the Macro press Alt and the number you selected for the macro. When you invoke a Macro (Alt-number) you will see the Key # and Macro number displayed in the upper right of the screen (very briefly because Macros execute very quickly). While ZD86 is executing a Macro, hitting Alt-S will abort the Macro play back. At this point the Macro is only temporary for this run of ZD86. To make it permanent so that you can use the Macro again the next time you run ZD86, choose Menu - Install selection, Save Macros or Save Everything. To chain Macros include the keystroke Alt-Number(of the Macro you wish to chain) at the end of the Macro you are defining. You will receive a message indicating that the Macros are chained. Make sure you do this on or before Key #100. If you key in 100 keystrokes you will receive the message "Maximum macro length reached - recording ended". Your first 100 keystrokes were recorded, however. Hit Esc to clear the error box. To replace a Macro simply record a new Macro with the same number. To guard against accidental erasure, when you invoke Macro recording Macros in use are indicated by a check mark. To see what keystrokes have been recorded a special utility, Zmacros, is provided to registered users to display the contents of all Macros. Simply type Zmacros ZD86 from DOS to produce a listing which you can look at on the screen, or redirect to the printer or a file. - 24 - 3.4.2 Graphics Debugging ------------------------ Special restrictions apply when using ZD86 for graphics programs. Debugging programs using any video mode works, but the User Application Screen is lost whenever control is returned to ZD86. However, ZD86 supports display saving during debugging of VGA 13h mode (320x200x256). To use this feature invoke ZD86 with the command line option /VGA13h. It will require an additional 64K of memory. The Graphics Video Memory area will not appear correctly in the Dump or Variable Windows because the Debug screen is in text mode and the video memory area becomes read-only except when graphics mode is active. The Screen Swap option must be set to Always or results may be incorrect for the same reason (no warning is given by the system on a write failure to video memory). The User Application Screen will display the graphics properly, however, the Output Window of the ZD86 Debugging Environment will not display graphics. - 25 - 4.0 Special Notes ----------------- Several areas of debugging and ZD86 features require special clarification and are discussed below. 4.1 Disassembly, Moving Backwards --------------------------------- Any disassembler can have difficulty moving backwards through memory because the interpretation of memory bytes into disassembled code is ambiguous unless you have a fixed starting point. This difficulty occurs because addresses and data in the code area often coincidentally have a valid assembly language interpretation. This is not a problem moving forward from a known starting point in the code area because the Assembler syntax rules limit the operand lengths and locations and therefore a unique, correct disassembly can be guaranteed. If you encounter a problem while moving backwards in the code window press Ctrl-up-arrow or Ctrl-down-arrow which will shift the disassembly by one byte each time until the valid code is displayed. 4.2 Procedure Step Runaway -------------------------- Procedure stepping is designed to stop at the next statement following a REP, LOOP or procedure CALL. If within the procedure the code causes a jump to some other location such that the next statement following the CALL is not encountered, the program will continue to execute until the next breakpoint or the end of the program, whichever is encountered first. 4.3 Status Line Help -------------------- The status line displays many, but not all, of the most important keys and their function depending on where you are in the ZD86 Debugging Environment. There may be other options available. 4.4 Symbolic Label Offsets -------------------------- When using Symbolic Labels only the Offset is stored. If you are working on a very large program, such as the assembly version of a higher level language source, your code may span more than one segment. If this occurs you may encounter spurious labels in the Code Window wherein a Label from one segment will appear at the same offset location in another segment. 4.5 Symbols non-Case Sensitive ------------------------------ - 26 - Symbol name entering is not case sensitive in ZD86 so that if the only difference between two labels is case ZD86 considers them interchangeable. It is best to use symbols in your source code that differ by something other than case. 4.6 Command Line Redirection ---------------------------- If you wish to use DOS redirection for the program you are debugging, you must type the redirection to your program on the command line when invoking ZD86. Redirection will not work when invoked from within the ZD86 Debugging Environment using the Load Program option from the Menu - File selection. Exit ZD86 and invoke it with ZD86 (program name) (redirection symbol, filename) - 27 - 5.0 Utilities ------------- Six utilities come with ZD86 to support and enhance the quality of the debugger. Three of them convert files produced by your assembler or linker into .Z86 files which provide symbolic debugging information to ZD86. The other three utilities provide other helpful functions: listing all the symbols stored in a .Z86 file, showing all the macros stored in your copy of ZD86, and copying configuration information from one copy of ZD86 to another copy of ZD86. Only two of the utilities come with the unregistered copy of ZD86: Lst-Z86 and Sym-Z86. The other utilities remain incentive for you to register ZD86--see Section 1.2. 5.1 Lst-Z86 ----------- The purpose of Lst-Z86 is to take a .Lst file output from TASM or MASM and write a .Z86 file containing all the symbols in your program. Like all of the utilities, Lst-Z86 is command line driven. The format for running Lst-Z86 is Lst-Z86 d:\path\filespec[.lst] The filespec can contain wildcards, and the .Lst is optional on the end. 5.2 Sym-Z86 ----------- Sym-Z86 is specialized for use with A86 .Sym files. A86 outputs .Sym files whenever it assembles any code, unless you specify -S on the A86 command line. Sym-Z86 will take the .Sym file and convert it to a .Z86 file for symbolic debugging in ZD86. ZD86 is one of only two debuggers in existence that allow you to symbolically debug programs written in A86 from the .Sym file. The format for running Sym-Z86 is Sym-Z86 d:\path\filespec[.sym] Again, the filespec can contain wildcards, and the .Lst is optional on the end. 5.3 Map-Z86 ----------- When writing programs in a high level language or a multiple module program in assembly language, a .Map file is often created by the linker. Map-Z86 takes the public symbols from the .Map file and writes a .Z86 which ZD86 can use. The format for - 28 - running Map-Z86 is Map-Z86 d:\path\filespec[.map] 5.4 ListZ86 ----------- After creating a .Z86 file with Lst-Z86, Sym-Z86, or Map-Z86 you may want to see what symbols were taken and stored in the .Z86 file. What ListZ86 does is list out all of your symbols and their values, first sorted by symbol value, and then sorted by name. The format for running ListZ86 is ListZ86 d:\path\filespec[.Z86] 5.5 Zmacros ----------- Recording long macros can be a difficult job, and remembering what they do even harder. Zmacros helps be listing out all the saved macros in a copy of ZD86, one key at a time. It tells you the scan code and ASCII code of each key, and the key's name if it is a non-alphanumeric key. The format for running Zmacros is Zmacros d:\path\ZD86[.com] 5.6 ZD86upgr ------------ Configuring all your colors, settings, macros, and function keys in ZD86 can take a decent amount of time, considering how much can be configured. And once you have done it on your unregistered copy of ZD86, you definitely do not want to do it again. That is exactly what ZD86upgr does for you: it takes all the configuration information from one copy of ZD86, and saves it all into another (possibly registered copy) of ZD86. The format for running ZD86upgr is ZD86upgr d:\path\zd86[.com] d:\path\zd86[.com] The first file will be updated with the configuration in the second. - 29 - 6.0 Registration Form --------------------- Name __________________________________________________ Street Address __________________________________________________ City ______________________ State _____ Zip ___________ Where did you get ZD86? _________________________________________ ZanySoft Debugger, version 1.0 ______ I am sending you $25 registration cost. I use ZD86 on one machine and would like you to send me a disk with the registered version of ZD86. Disk size: _____ 3.5" _____ 5.25" If sending a check, make it out to Christopher Kirmse. For orders of more than one copy, send me a letter and we will work out a suitable price. Please send this form and payment to: ZanySoft 9303 Arabian Ave. Vienna, VA 22182 Write any comments below: - 30 -